Expand description
Weave deltas, inspired by SCCS.
The SCCS revision control system is one of the oldest source code management systems (1973). Although many of its concepts are quite dated in these days of git, the underlying “weave” delta format it used turns out to be a good way of representing multiple versions of data that differ only in parts.
This package implements a weave-based storage of “plain text”, where plain text consists of lines of UTF-8 printable characters separated by a newline.
The format is similar to SCCS, but with no constraints to keep what are relatively poor design decisions from SCCS, such as putting a checksum at the top of the file, and using limited-sized field for values such as the number of lines in a file, or the use of 2-digit years. However, the main body of the weaved file, that which describes inserts and deletes is the same, and allows us to test this version by comparing with the storage of sccs.
Weave files are written using NewWeave, which works like a regular file writer. The file
itself has a small amount of surrounding metadata, but is otherwise mostly just the contents of
the initial file.
Adding a delta to a weave file is done with the DeltaWriter. This is also written to, as a
regular file, and then DeltaWriter::close method will extract a base revision and use the
diff command to write a new version of the weave. The close method will make several
temporary files in the process.
The weave data is stored using a NamingConvention, a trait that manages a related
collection of files, and temp files. SimpleNaming is a basic representation of this that
has a base name, a backup file, and some temporary files. The data in the file can be
compressed.
Structs
Information about a single delta.
A DeltaWriter is used to write a new delta. Data should be written to the writer, and then the
close method called to update the weave file with the new delta.
The header placed at the beginning of the each weave file. The deltas correspond with the
deltas checked in. Note that the value passed to crate::PullParser::new should be the number
field of DeltaInfo and not the index in the deltas vec.
A builder for a new weave file. The data should be written as a writer. Closing the weaver will finish up the write and move the new file into place. If the weaver is just dropped, the file will not be moved into place.
A Parser is used to process a weave file. This is a wrapper around the pull parser that invokes a push parser.
The pull parser is the intended way of reading from weave files. After opening a particular
delta with PullParser::new, the parser can be used as an iterator, to return Entry values. In
particular, the entries for Entry::Plain where keep is true will be the lines of the
weave that comprise the expected delta.
The SimpleNaming is a NamingConvention that has a basename, with the main file having a specified extension, the backup file having a “.bak” extension, and the temp files using a numbered extension starting with “.0”. If the names are intended to be compressed, a “.gz” suffix can also be added.
Something we can write into, that remembers its name. The writer is boxed because the writer may be compressed.
Enums
Traits
A naming convention provides utilities needed to find the involved files, and construct temporary files as part of writing the new weave. The underlying object should keep the path and base name.
A Sink is a place that a parsed weave can be sent to. The insert/delete/end commands match
those in the weave file, and plain are the lines of data. With each plain is a flag
indicating if that line should be included in the output (all lines are called, so that updates
can use this same code). All methods return a result, with the Err value stopping the parse.
Note that the default implementations just return success, and ignore the result.
Functions
Retrieve the last delta in the weave file. Will panic if the weave file is malformed and contains no revisions.
Read the header from a weave file.